Issue #4551 Changed mock docks to use sphinx #4569

anubhavsinha98 · 2018-08-24T20:51:46Z

No description provided.

stsewd · 2018-08-24T21:05:26Z

docs/faq.rst


-.. Tip:: The library ``unittest.mock`` was introduced on python 3.3. On earlier versions install the ``mock`` library
-    from PyPI with (ie ``pip install mock``) and replace the above import::
+Changed in version 1.6: This config value only requires to declare the top-level modules that should be mocked.


We shouldn't put this here, instead, link to the http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports

Ok I should just link to the document of sphinx rather than pasting it and remove the earlier workaround.

@stsewd changed!

stsewd · 2018-08-24T23:28:21Z

docs/faq.rst


-    import sys
-    from unittest.mock import MagicMock
+autodoc_mock_imports


We could start this with something more explicit, like "You can use this feature included in autodoc to mock..." where the feature name would link to the sphinx's docs. Thanks for contributing btw :)

anubhavsinha98 · 2018-08-25T10:22:21Z

Hey @stsewd done some changes is it ok now?

anubhavsinha98 · 2018-08-27T11:38:10Z

Hey @stsewd check out the PR?

stsewd · 2018-08-27T15:43:52Z

docs/faq.rst

@@ -65,27 +65,8 @@ I get import errors on libraries that depend on C modules

 This happens because our build system doesn't have the dependencies for building your project. This happens with things like libevent and mysql, and other python things that depend on C libraries. We can't support installing random C binaries on our system, so there is another way to fix these imports.

-You can mock out the imports for these modules in your ``conf.py`` with the following snippet::
+You can use this feature included in autodoc to mock http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports.


Maybe we can put the name of the feature (and the link to it here) and end with "..to mock your dependencies."

Echoing proper format for linking instead of naked link

I have removed the naked link issue!

agjohnson

Thanks for the contribution, noted a couple spots to clean up the change

agjohnson · 2018-08-27T20:17:10Z

docs/faq.rst

-
-        from mock import Mock as MagicMock
-
-If such libraries are installed via ``setup.py``, you also will need to remove all the C-dependent libraries from your ``install_requires`` in the RTD environment.


We should however keep this notice, as a lot of folks have mocked their dependencies in the past, but not performed this step, assuming mocking was enough.

@agjohnson , can you suggest what notice I can create for the folks?
For eg. "There is a new feature "autodock_mock_imports" for mocking the dependencies, the earlier feature present was a complex one".
Please suggest!

I think this can be something like: "If you are mocking your dependencies using the mock library and such... "

Now check it @stsewd !

We probably just need to communicate that if you mock dependencies, in whatever fashion, that you aren't installing those dependencies either. The original copy just needs to be updated to match the new context i think.

agjohnson · 2018-08-27T20:18:03Z

docs/faq.rst

@@ -65,27 +65,8 @@ I get import errors on libraries that depend on C modules

 This happens because our build system doesn't have the dependencies for building your project. This happens with things like libevent and mysql, and other python things that depend on C libraries. We can't support installing random C binaries on our system, so there is another way to fix these imports.

-You can mock out the imports for these modules in your ``conf.py`` with the following snippet::
+You can use this feature included in autodoc to mock http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports.


Echoing proper format for linking instead of naked link

stsewd · 2018-08-27T22:56:14Z

docs/faq.rst

@@ -65,7 +65,7 @@ I get import errors on libraries that depend on C modules

 This happens because our build system doesn't have the dependencies for building your project. This happens with things like libevent and mysql, and other python things that depend on C libraries. We can't support installing random C binaries on our system, so there is another way to fix these imports.

-You can use this feature `autodoc_mock_imports`_ to mock your dependencies.
+If you are mocking your dependencies using the mock library, then you can also use this feature `autodoc_mock_imports`_ to mock your dependencies.


So, what Anthony mean, was to keep both paragraphs. The link to autodoc_mock_imports and the note about the previous usage of the mock lib. Sorry about the confusion.

anubhavsinha98 · 2018-08-28T21:16:28Z

Now check @stsewd and @agjohnson !

stsewd · 2018-08-28T21:23:25Z

docs/faq.rst

@@ -87,6 +86,11 @@ Of course, replacing `MOCK_MODULES` with the modules that you want to mock out.

 If such libraries are installed via ``setup.py``, you also will need to remove all the C-dependent libraries from your ``install_requires`` in the RTD environment.

+If you are mocking your dependencies using the mock library, then you can also use this feature `autodoc_mock_imports`_ to mock your dependencies.


I think the autodoc feature is independent from the mock library and should be pointed first (as we want new users to use that method), the previous paragraph was ok btw, you only needed to keep the another paragraph

anubhavsinha98 · 2018-08-28T21:52:11Z

Check now @stsewd , I have marked the autodock feature on the top and then the previous one below.

agjohnson

Looks better. Just clarifying what we want to communicate to users.

agjohnson · 2018-09-05T21:40:42Z

docs/faq.rst

-You can mock out the imports for these modules in your ``conf.py`` with the following snippet::
+If you are mocking your dependencies without using the mock library, then you can use this feature `autodoc_mock_imports`_ to mock your dependencies.
+
+.. _autodock_mock_imports: http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports


Link label is wrong here, should be autodoc_mock_imports.

I can't recognize, I think it's okay.

There is a typo autodocK

agjohnson · 2018-09-05T21:42:46Z

docs/faq.rst

@@ -65,7 +65,13 @@ I get import errors on libraries that depend on C modules

 This happens because our build system doesn't have the dependencies for building your project. This happens with things like libevent and mysql, and other python things that depend on C libraries. We can't support installing random C binaries on our system, so there is another way to fix these imports.

-You can mock out the imports for these modules in your ``conf.py`` with the following snippet::
+If you are mocking your dependencies without using the mock library, then you can use this feature `autodoc_mock_imports`_ to mock your dependencies.


I think what we're wanting to say here is "The recommended method of mocking your libraries is to use the autodoc_mock_imports config option", not "if you are .."

Yes I am changing it!

@agjohnson I think its fine as it is the syntax for the removing the naked link.

What Anthony says is that we should encourage people to use the autodoc_mock_imports method

…s.org into anubhavsinha98-master

ericholscher

Pushed some small changes to get this merged. Thanks for the contribution!

codecov · 2018-11-01T13:30:11Z

Codecov Report

Merging #4569 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #4569   +/-   ##
=======================================
  Coverage   76.33%   76.33%           
=======================================
  Files         158      158           
  Lines        9968     9968           
  Branches     1258     1258           
=======================================
  Hits         7609     7609           
  Misses       2018     2018           
  Partials      341      341

Codician_Anubhav added 3 commits August 25, 2018 02:09

FirstIssue

4e1059c

FirstIssue

866c7eb

FirstIssue

7ffeeab

anubhavsinha98 mentioned this pull request Aug 24, 2018

Change our mock docs to use sphinx #4551

Closed

stsewd reviewed Aug 24, 2018

View reviewed changes

FirstIssue

77fba14

anubhavsinha98 changed the title ~~Issue #4551~~ Issue #4551 Changed mock docks to use sphinx Aug 24, 2018

stsewd reviewed Aug 24, 2018

View reviewed changes

changes

6f4be2b

stsewd reviewed Aug 27, 2018

View reviewed changes

agjohnson requested changes Aug 27, 2018

View reviewed changes

agjohnson added this to the Better user documentation milestone Aug 27, 2018

Codician_Anubhav added 2 commits August 28, 2018 03:03

nakedlinkremoved

c8eb0c4

Next

cdcf0d0

stsewd reviewed Aug 27, 2018

View reviewed changes

next

e8a357a

stsewd reviewed Aug 28, 2018

View reviewed changes

another

a875a97

agjohnson added the PR: work in progress Pull request is not ready for full review label Aug 28, 2018

agjohnson reviewed Sep 5, 2018

View reviewed changes

ericholscher added 4 commits November 1, 2018 08:19

Merge branch 'master' of https://github.com/anubhavsinha98/readthedoc…

2fa6696

…s.org into anubhavsinha98-master

Update faq grammar and links

dd89c54

Merge remote-tracking branch 'origin/master' into anubhavsinha98-master

5cbc554

Remove stray newline

9f0ac34

ericholscher approved these changes Nov 1, 2018

View reviewed changes

More grammar cleanup

96aba32

ericholscher merged commit cb215c2 into readthedocs:master Nov 1, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Issue #4551 Changed mock docks to use sphinx #4569

Issue #4551 Changed mock docks to use sphinx #4569

anubhavsinha98 commented Aug 24, 2018

stsewd Aug 24, 2018

anubhavsinha98 Aug 24, 2018

anubhavsinha98 Aug 24, 2018

stsewd Aug 24, 2018

anubhavsinha98 commented Aug 25, 2018

anubhavsinha98 commented Aug 27, 2018

stsewd Aug 27, 2018

agjohnson Aug 27, 2018

anubhavsinha98 Aug 27, 2018

agjohnson left a comment

agjohnson Aug 27, 2018

anubhavsinha98 Aug 27, 2018

stsewd Aug 27, 2018

anubhavsinha98 Aug 27, 2018

agjohnson Aug 27, 2018

agjohnson Aug 27, 2018

stsewd Aug 27, 2018 •

edited

anubhavsinha98 commented Aug 28, 2018

stsewd Aug 28, 2018

anubhavsinha98 commented Aug 28, 2018

agjohnson left a comment

agjohnson Sep 5, 2018

anubhavsinha98 Sep 6, 2018

stsewd Sep 10, 2018

agjohnson Sep 5, 2018

anubhavsinha98 Sep 6, 2018

anubhavsinha98 Sep 8, 2018

stsewd Sep 10, 2018

ericholscher left a comment

codecov bot commented Nov 1, 2018


		from mock import Mock as MagicMock

		If such libraries are installed via ``setup.py``, you also will need to remove all the C-dependent libraries from your ``install_requires`` in the RTD environment.

		@@ -87,6 +86,11 @@ Of course, replacing `MOCK_MODULES` with the modules that you want to mock out.

		If such libraries are installed via ``setup.py``, you also will need to remove all the C-dependent libraries from your ``install_requires`` in the RTD environment.

		If you are mocking your dependencies using the mock library, then you can also use this feature `autodoc_mock_imports`_ to mock your dependencies.

Issue #4551 Changed mock docks to use sphinx #4569

Issue #4551 Changed mock docks to use sphinx #4569

Conversation

anubhavsinha98 commented Aug 24, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

anubhavsinha98 commented Aug 25, 2018

anubhavsinha98 commented Aug 27, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

agjohnson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stsewd Aug 27, 2018 • edited

Choose a reason for hiding this comment

anubhavsinha98 commented Aug 28, 2018

Choose a reason for hiding this comment

anubhavsinha98 commented Aug 28, 2018

agjohnson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericholscher left a comment

Choose a reason for hiding this comment

codecov bot commented Nov 1, 2018

Codecov Report

stsewd Aug 27, 2018 •

edited